WebSocket ready states are numeric constants representing the connection's current status: 0 (CONNECTING), 1 (OPEN), 2 (CLOSING), and 3 (CLOSED), which can be accessed via the WebSocket.readyState property.
The WebSocket.readyState property provides a way to programmatically determine the current state of a WebSocket connection. This is essential for robust applications that need to handle connection failures, send messages only when the connection is open, or implement reconnection logic. The readyState is a read-only integer that changes throughout the connection lifecycle, from initial handshake through active communication to final closure.
0 - CONNECTING: The connection is being established. The handshake has not yet completed. This is the initial state when the WebSocket object is created .
1 - OPEN: The connection is established and ready for communication. Both text and binary data can be sent and received in this state .
2 - CLOSING: The connection is in the process of closing. Either the client or server initiated a close handshake, but it hasn't completed yet .
3 - CLOSED: The connection is closed or could not be opened. This is the final state after a successful close or after a connection failure .
The ready state is particularly important for sending messages. Attempting to send data when the connection is not in the OPEN state will throw an error. Robust implementations always check the ready state before sending, and often implement queuing mechanisms for messages that arrive while connecting or reconnecting.
CONNECTING → OPEN: Occurs when the handshake completes successfully and the connection is ready .
OPEN → CLOSING: Triggered when either side initiates a close (via
socket.close()or server close frame) .CLOSING → CLOSED: Happens when the close handshake completes and the underlying TCP connection terminates .
CONNECTING → CLOSED: Can happen if the handshake fails (network error, server rejects, timeout) .
OPEN → CLOSED: Immediate transition if the connection fails unexpectedly (network interruption, server crash) without going through CLOSING .
Understanding ready states is crucial for debugging WebSocket issues. For example, if messages aren't sending, checking readyState can quickly reveal whether the connection is still handshaking (0), closed (3), or in the process of closing (2). Browser DevTools also show the current state in the Network tab's WebSocket inspector, along with frame history and timing information. When implementing reconnection logic, the ready state helps determine whether to attempt immediate reconnection (if CLOSED) or wait for a pending connection to complete (if CONNECTING).
The WebSocket ready states are a simple but essential part of the API. By providing a clear view of connection lifecycle, they enable developers to build resilient real-time applications that handle network interruptions, server restarts, and intermittent connectivity gracefully. Combined with the close event's code and reason properties, ready states give you complete visibility into what your WebSocket connection is doing at any moment.